Resolves #196

Hi! I ran into the issue that numpydoc does not support typehints before Christmas, so I decided to have a crack at it. I have tried multiple different approaches (not in this git history), especially trying to combine numpydoc with sphinx-autodoc-typehints, but what I finally settled on is to make use of numpydoc's powerful class system (I have found that the data representation of numpydoc and sphinx-autodoc-typehints are largely incompatible).

My implementation edits the _parse_param_list method - responsible for creating the docstrings for Parameters, Other Parameters, Attributes, Methods, Returns, Yields, Raises, and Receives sections - so that a type can be obtained from the type hint if one is not specified in the docstring (btw, I believe it should be relatively simple to implement #356 following a similar method). This means that the type hints can be supported for all those sections with minimal code. The way this works is defined in a new method, _get_type_from_signature, which by default on NumpyDocString only returns an empty string (no type). The actual type inference is implemented on the subclasses:

FunctionDoc

Getting type hints for functions is the easier task since we can rely fully on inspect.signature. Firstly, the signature is obtained in __init__ to avoid recomputing it at every iteration of _parse_param_list. All that is then necessary in _get_type_from_signature is to return the type hint associated with the argument name, provided that the function has a signature and that the type hint is set.

There is a small complication in that multiple parameters can be combined into one entry, but all that is necessary to support that is to ensure that all the combined parameters are type-hinted as the same type, otherwise return no type.

ClassDoc

At the basic level, the type hints for classes are similar to FunctionDoc and the code is therefore repeated (there is potentially room for optimisation where the code could be pulled out to NumpyDocString, should that be desirable). However, there is an additional complication in that the class documentation may contain the attributes (which may be @property) and therefore are not part of the __init__ signature. This required an additional method, _find_type_hints:

• First is handled the case where the arg_name is an attribute with a type annotation (typing.get_type_hints handles unwrapping etc.)
  • Note that the _annotation_to_string function handles the various possiblities for what the annotation can be - missing, a class instance, or a type from the typing module.

        type_hints = get_type_hints(obj, include_extras=True)
        try:
            annotation = type_hints[arg_name]
        except KeyError:
            ...

        return _annotation_to_string(annotation)

def _annotation_to_string(annotation) -> str:
    if annotation == inspect.Signature.empty:
        return ""
    elif type(annotation) is type:
        return str(annotation.__name__)
    else:
        return str(annotation)

• In the ..., the remaining options are that the arg_name doesn't exist, handled via:

            try:
                attr = getattr(obj, arg_name)
            except AttributeError:
                return ""

• Or that it is a property, in which case inspect.signature is used to obtain the return type (note that in the case of non-standard properties, this block is not triggered):

            if isinstant(attr, property):
                try:
                    signature = inspect.signature(attr.fget)
                except ValueError:
                    return ""

                return _annotation_to_string(signature.return_annotation)

• Or that it is a class attribute without an annotation (but with the value set), in which case it can be extracted:

            return type(attr).__name__

Once again, though, the above is further complicated by the fact parameters can be combined (not sure whether it is valid to combine attributes as well, but this implementation can handle that as well). This is solved again by ensuring all the combined parameters/attributes are of the same type, as returned by _find_type_hints.

Robustness

From my testing, this implementation is able to handle everything my other projects could throw at it, but I would not be surprised if there are edge cases where it breaks down. Regardless, though, I think it might be possible to increase the robustness of my implementation by using some of the type-extraction functions from sphinx-autodoc-typehints (whether by depending on it as a whole, or by copying the relevant functions, I am unsure), such as get_annotation_args or format_annotation.

Conclusion

Please let me know what you think! I am keen to get numpydoc working with type annotations, and I believe that this implementation is a straightforward way to do that, but I am curious what your plans are for this issue.

Notes

• Support type annotations in Returns and Yields sections #356 return type hints is not implemented here since I think it requires more discussion about the spec, but happy to do that as well
• this implementation only inserts type, not the default values, but adding the defaults from the signature as well should be simple - not sure whether to add it here or separate PR though